% vim: ts=4:sw=4
\lstset{ %
language=C,                % choose the language of the code
basicstyle=\footnotesize,       % the size of the fonts that are used for the code
numbers=left,                   % where to put the line-numbers
numberstyle=\footnotesize,      % the size of the fonts that are used for the line-numbers
stepnumber=2,                   % the step between two line-numbers. If it's 1 each line will be numbered
numbersep=5pt,                  % how far the line-numbers are from the code
backgroundcolor=\color{white},  % choose the background color. You must add \usepackage{color}
showspaces=false,               % show spaces adding particular underscores
showstringspaces=false,         % underline spaces within strings
showtabs=false,                 % show tabs within strings adding particular underscores
frame=single,	                % adds a frame around the code
tabsize=2,	                % sets default tabsize to 2 spaces
captionpos=b,                   % sets the caption-position to bottom
breaklines=true,                % sets automatic line breaking
breakatwhitespace=false,        % sets if automatic breaks should only happen at whitespace
title=\lstname,                 % show the filename of files included with \lstinputlisting; also try caption instead of title
escapeinside={\%*}{*},          % if you want to add a comment within your code
morekeywords={*,...}            % if you want to add more keywords to the set
}


\chapter{Introduction}

To simplify the development of user applications and to abstract hardware specific operations and complexity away from these, PORN-OS comes with a custom API.

The API is made available to the application programmer as a set of C-functions defined in the api.h file.

The system call functions have french names to express the OS' distinctness from existing Unices or other existing operating systems.

\chapter{System calls}

\section{fourchette}

\texttt{int32\_t fourchette(int32\_t priority, char* progname, int32\_t parameters[4])}

\subsection*{Description}
This command creates a new process executing the program received as a parameter (\texttt{progname}).

\subsection*{Parameters}The parameters that have to be passed are: 
\begin{itemize}
 \item \textbf{priority}: an unsigned 32 bit integer containing the priority 
 \item \textbf{progname}: a string of characters containing the program that is to be executed by the new process
 \item \textbf{parameters[4]}: an array of 4 integers that are to be passed to the process as parameters. The function accepts that this parameter be NULL. 
\end{itemize}

\subsection*{Return values}
If the call is successful, it returns the pid of the process that has been created. A pid is always positive, so a negative result is an error. The following errors can occur:

\begin{itemize}
	\item OUT\_OF\_MEMORY: the system has not enough memory for a new process.
	\item UNKNOWN\_PROGRAM: the specified program does not exist.
	\item WRONG\_PRIORITY: the specified priority is not supported (must be between 1 and MAX\_PRIORITY).
\end{itemize}

\subsection*{Examples}
  \begin{lstlisting}
int child = fourchette(12, "oom", NULL);
char args[4] = {5,3,0,0};
int pid = fourchette(12, "dinner", args); 
 \end{lstlisting}

\section{tuer}

\texttt{int32\_t tuer(int32\_t pid, int32\_t exit\_code)}

\subsection*{Description}
This command kills the specified process and ensures that all the resources used by the process are reclaimed by the system.

\subsection*{Parameters}
\begin{itemize}
 \item \textbf{pid}: an 32 bit integer containing the PID of the process that is about to be terminated
 \item \textbf{exit\_code}:the value which is transmitted to the parent and/or supervisors (if any)
\end{itemize}

\subsection*{Return values}
This function returns the following codes:
\begin{itemize}
	\item SUCCESS: the call has been successful
	\item OUT\_OF\_MEMORY: can happen when the process is supervised and there is not enough memory for a new message. The process is still killed.
	\item FAILURE: something went wrong and the process has not been killed. Trying to kill an unexisting process (or a zombie) gives this result.
\end{itemize}

\subsection*{Examples} 
 \begin{lstlisting}
int code = tuer(3, 4);
 \end{lstlisting}

\section{quitter}

\texttt{int32\_t quitter(int32\_t exit\_code)}

\subsection*{Description}
This function kills the caller like if it invoked tuer() on itself.

\subsection*{Parameters}
\begin{itemize}
 \item \textbf{exit\_code}:the value which is transmitted to the parent and/or supervisors (if any)
\end{itemize}

\subsection*{Return values}
The same values as tuer() if the call failed. It does not return in case of success.
\begin{itemize}
	\item OUT\_OF\_MEMORY: can happen when the process is supervised and there is not enough memory for a new message. The process is still killed.
	\item FAILURE: something went wrong and the process has not been killed. Trying to kill an unexisting process (or a zombie) gives this result.
\end{itemize}

\subsection*{Examples}
 \begin{lstlisting}
quitter(3);
 \end{lstlisting}

\section{quitter\_success}

\texttt{int32\_t quitter\_succes()}

\subsection*{Description}
This function does the same as quitter but always uses the code SUCCESS instead an exit\_code specified by the programmer.

\subsection*{Parameters}
none

\subsection*{Return values}
\begin{itemize}
	\item OUT\_OF\_MEMORY: can happen when the process is supervised and there is not enough memory for a new message. The process is still killed.
	\item FAILURE: something went wrong and the process has not been killed. Trying to kill an unexisting process (or a zombie) gives this result.
\end{itemize}

\subsection*{Examples}
 \begin{lstlisting}
quitter_success();
 \end{lstlisting}

\section{changer\_priorite}

\texttt{int32\_t changer\_priorite(int32\_t pid, int32\_t priority)}

\subsection*{Description}
This function changes the priority of a process.

\subsection*{Parameters}
\begin{itemize}
 \item \textbf{pid}: the PID of the process whose priority is about to be changed
 \item \textbf{priority}: the new priority
\end{itemize}

\subsection*{Return values}
\begin{itemize}
	\item SUCCESS: the priority has been changed
	\item FAILURE: the specified process has not been found or some other error occured
	\item WRONG\_PRIORITY: the new priority is not correct (must be between 1 and MAX\_PRIORITY, which is 42 at the time of writing)
\end{itemize}

\subsection*{Examples}
  \begin{lstlisting}
int code = changer_priorite(2, 42);
int code = changer_priorite(some_pid, 17);
int code = changer_priorite(myPid, 1);
int code = changer_priorite(pid, 0); //WRONG_PRIORITY !!
 \end{lstlisting}

\section{obtenir\_programme}

\texttt{char* obtenir\_programme(int32\_t pid)}

\subsection*{Description}
This function returns the name of the program being executed by a process, by pid. 

\subsection*{Parameters}
\begin{itemize}
 \item \textbf{pid}: the pid of the process in which we are interested in finding the name of the program it executes.
\end{itemize} 
\subsection*{Return values}
It returns the name of the program executed by a specified pid or NULL if the memory for it could not be allocated.

\subsection*{Examples}
 \begin{lstlisting}
char* name = obtenir_programme(2);
 \end{lstlisting}

\section{obtenir\_pid}

\texttt{int32\_t obtenir\_pid()}

\subsection*{Description}
This function returns the pid of the current (that means calling) process.
\subsection*{Parameters}
none
\subsection*{Return values}
The caller's pid. This call never fails.
\subsection*{Examples}
 \begin{lstlisting}
int pid = obtenir_pid();
 \end{lstlisting}


\section{obtenir\_priorite}

\texttt{int32\_t obtenir\_priorite(int32\_t pid)}

\subsection*{Description}
The function returns the priority of the running process.

\subsection*{Parameters}
\begin{itemize}
	\item \textbf{pid}: the PID of the process in which we are interested of getting its state
\end{itemize}
\subsection*{Return values}
There are two possible return values, the priority of the specified process (an integer between 1 and MAX\_PRIORITY) or FAILURE if the process is not found.
\subsection*{Examples}
 \begin{lstlisting}
int my_priority = obtenir_priorite(obtenir_pid());
int some_priority = obtenir_priorite(17);
 \end{lstlisting}

\section{obtenir\_etat}

\texttt{int32\_t obtenir\_etat(int32\_t pid)}

\subsection*{Description}
This function returns the state of the specified process. The states that can be returned are defined in states.h and are the following: 

\subsection*{Parameters}
\begin{itemize}
	\item \textbf{pid}: the PID of the process in which we are interested of getting its state
\end{itemize}
The following states exist and can be returned:
\begin{itemize}
 \item \textbf{READY\_STATE}: the process is in the ready queue
 \item \textbf{RUNNING\_STATE}: the process has been allocated the processor
 \item \textbf{BLOCKED\_STATE}: the process is blocked
 \item \textbf{DELAYED\_STATE}: the process is delayed
 \item \textbf{WAITING\_IO\_UART\_STATE}: the process waits for its turn in the UART queue
 \item \textbf{DOING\_IO\_UART\_STATE}: the process uses the UART
 \item \textbf{WAITING\_CHILD\_TERM\_STATE}: the process waits for one of its children to terminate
 \item \textbf{ZOMBIE\_STATE}: the process has terminated and waits for its parent to get its return value
\end{itemize}
\subsection*{Return values}
The state of the specified process or FAILURE if the process does not exist.

\subsection*{Examples}
\begin{lstlisting}
int state = obtenir_etat(3);
if(state == BLOCKED_STATE)
...
 \end{lstlisting}


\section{obtenir\_parent}

\texttt{int32\_t obtenir\_parent(int32\_t pid)}

\subsection*{Description}
The function is given a process pid and returns the pid of the parent of said process. 
\subsection*{Parameters}
\begin{itemize}
	\item \textbf{pid}: the PID of the process in which we are interested of getting its parent
\end{itemize}
\subsection*{Return values}
The pid of processes' parent or OUT\_OF\_MEMORY  in case of failure.
\subsection*{Examples}
\begin{lstlisting}
int parent_pid = obtenir_parent(some_pid);
int p_pid = obtenir_parent(obtenir_pid());
 \end{lstlisting}


\section{obtenir\_tous\_pid}

\texttt{int32\_t* obtenir\_tous\_pid(int32\_t* length)}

\subsection*{Description}
This function returns the list of all the processes in the system.
\subsection*{Parameters}
\begin{itemize}
  \item \textbf{length}: the length of the array that will be returned (pointer).
\end{itemize}
\subsection*{Return values}
A pointer to an array of pids (integers) or NULL if OUT\_OF\_MEMORY
\subsection*{Examples}
\begin{lstlisting}
int len,i,pid;
int* all_pid = obtenir_tous_pid(&len);
if(all_pid == NULL){
    ecrire("Not enough memory.\n");
    return;
}
for(i=0;i<len;i++){
    pid = all_pid[i];
    ...
}
\end{lstlisting}


\section{ecrire}

\texttt{int32\_t ecrire(const char* data)}

\subsection*{Description}
The function prints a string on the serial console (TTY0).
\subsection*{Parameters}
\begin{itemize}
    \item \textbf{data}: string that should be written to the console.
\end{itemize}
\subsection*{Return values}
Returns SUCCESS in the case of success and FAILURE otherwise.

\subsection*{Examples}
\begin{lstlisting}
ecrire("hello world\n");
\end{lstlisting}

\section{ecrire\_lcd}

\texttt{int32\_t ecrire\_lcd(const char* data)}

\subsection*{Description}
This function prints a string to the LCD attached to the malta board. This LCD can show at maximum 8 characters. Additional characters are omitted.
\subsection*{Parameters}
\begin{itemize}
    \item \textbf{data}: string that should be written to the LCD.
\end{itemize}

\subsection*{Return values}
Returns SUCCESS in the case of success and FAILURE otherwise.

\subsection*{Examples}
\begin{lstlisting}
char* text = "PORN-OS OR No OS!";
ecrire_LCD(text);
\end{lstlisting}


\section{lire}

\texttt{int32\_t lire(char* data, int length)}

\subsection*{Description}
Reads data from the console (TTY0). It reads up to length-1 characters or until a \textbackslash r is returned. It returns a NULL-terminated string.
\subsection*{Parameters}
\begin{itemize}
    \item \textbf{data}: string where the data read should be stored.
    \item \textbf{length}: maximum length of the data to read (minus 1).
\end{itemize}
\subsection*{Return values}
Returns SUCCESS in the case of success and FAILURE otherwise.
\subsection*{Examples}
 \begin{lstlisting}
#define MAX_CMD_LEN 81
char line[MAX_CMD_LEN];
if(lire(line, MAX_CMD_LEN) == FAILURE){
    ecrire("Shell: impossible to read input from user\n");
    quitter(FAILURE);
}
...
char c[20] = "Write something !\n";
int r = 0;
r = lire(c, 20);
\end{lstlisting}

\section{bloquer}

\texttt{int32\_t bloquer(int32\_t pid)}

\subsection*{Description}
Blocks the process with the pid passed as parameter. The process is taken out of the ready queue and its execution is stopped. The process can be later woken up by another process, using reveiller().
\subsection*{Parameters}
\begin{itemize}
    \item \textbf{pid}: pid of the process to block.
\end{itemize}
\subsection*{Return values}
Returns SUCCESS in the case of success and FAILURE otherwise.
\subsection*{Examples}
 \begin{lstlisting}
 bloquer(4);
 bloquer(obtenir_pid());
 \end{lstlisting}

\section{attendre}

\texttt{int32\_t attendre(int32\_t pid, int32\_t* status)}

\subsection*{Description}
The function waits for a specified process to terminate and returns the termination status. The PID being passed to the function needs to be one of the caller's children. 
\subsection*{Parameters}
\begin{itemize}
    \item \textbf{pid}: pid of the process to wait for.
    \item \textbf{status}: return value of the process that was waited for.
\end{itemize}
\subsection*{Return values}
Returns SUCCESS in the case of success and FAILURE otherwise.
Also returns status of the waited for process in the parameter status.

\subsection*{Examples}
\begin{lstlisting}
int status;
attendre(pid, &status);
...
if(attendre(some_pid, &status) == FAILURE) {
    ...
}
\end{lstlisting} 

\section{reveiller}

\texttt{int32\_t reveiller(int32\_t pid)}

\subsection*{Description}
The function is used to wake a process up which has been blocked or delayed. Waking up a delayed process immediately ends its waiting. The process changes into the \textbf{Ready} state and will resume executing according to its priority. 
\subsection*{Parameters}
\begin{itemize}
    \item \textbf{pid}: pid of the process to wake up.
\end{itemize}
\subsection*{Return values}
Returns SUCCESS in the case of success and FAILURE otherwise.
\subsection*{Examples}
\begin{lstlisting}
reveiller(pid);
...
if(reveiller(some_pid) == FAILURE) { 
    ...
}
\end{lstlisting} 

\section{retarder}

\texttt{int32\_t retarder(int32\_t pid, uint32\_t n)}

\subsection*{Description}
Delays the execution of a process for some time, specified in milliseconds. 
\subsection*{Parameters}
\begin{itemize}
    \item \textbf{pid}: pid of the process to delay.
    \item \textbf{time}: time in milliseconds to delay the process for.
\end{itemize}
\subsection*{Return values}
Returns SUCCESS in the case of success and FAILURE otherwise.
\subsection*{Examples}
\begin{lstlisting}
retarder(obtenir_pid(), 1700);
retarder(some_pid, random(&m_w,&m_z)%5000)
\end{lstlisting}


\section{allouer}

\texttt{void* allouer(int32\_t size)}

\subsection*{Description}
This function is given a number of bytes to allocate in the heap. It returns a pointer to the allocated area (the memory is allocated as a block).
\subsection*{Parameter}
\begin{itemize}
    \item \textbf{size}: size in bytes to allocate.
\end{itemize}
\subsection*{Return values}
Pointer to the allocated memory in case of SUCCESS, NULL otherwise.
\subsection*{Examples}
\begin{lstlisting}
current = allouer(sizeof(struct linked_list));
char* b = allouer(4*sizeof(char));
int32_t* node_pids = allouer(nb_procs*sizeof(int));
philos = allouer(num_philo*sizeof(int));
\end{lstlisting}

\section{liberer}

\texttt{int32\_t liberer(void* pointer)}

\subsection*{Description}
Frees the memory the pointer passed as parameter is pointing to.
\subsection*{Parameter}
\begin{itemize}
    \item \textbf{pointer}: pointer to the memory that should be freed.
\end{itemize}
\subsection*{Return values}
returns FAILURE if the parameter does not point to an area allocated by allouer, SUCCESS otherwise.
\subsection*{Examples}
 \begin{lstlisting}
char* some_chars = allouer(4*sizeof(char));
liberer(some_chars);
 \end{lstlisting}

\section{envoyer\_chaine}

\texttt{int32\_t envoyer\_chaine(int32\_t to, char* data, int32\_t priority)}

\subsection*{Description}
This sends a message containing a string, called message of type string. The string is copied into the message that is being sent, so the caller can free it if needed without affecting the receiver.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{to}: destination of the message to be sent to
 \item \textbf{data}: the string to be sent
 \item \textbf{priority}: priority of the message
\end{itemize}
\subsection*{Return values}
\begin{itemize}
	\item SUCCESS: the message has been sent
	\item FAILURE: something went wrong, eg. the process the message should be sent to does not exist
	\item WRONG\_PRIORITY: a message priority is an integer greater than 1
    \item OUT\_OF\_MEMORY: message could not be sent because there was not enough memory available
\end{itemize}
\subsection*{Examples}
\begin{lstlisting}
envoyer_chaine(obtenir_pid(), "Bonjour, toi\n",1);
if(envoyer_chaine(next_node_pid, s, 9) == OUT_OF_MEMORY) ...
\end{lstlisting}

\section{envoyer\_entier}

\texttt{int32\_t envoyer\_entier(int32\_t to, int32\_t data, int32\_t priority)}

\subsection*{Description}
Sends a message containing an integer, called message of type integer. Similar to envoyer\_chaine().
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{to}: destination of the message to be sent to
 \item \textbf{data}: the int to be sent
 \item \textbf{priority}: priority of the message
\end{itemize}
\subsection*{Return values}
\begin{itemize}
	\item SUCCESS: the message has been sent
	\item FAILURE: something went wrong, eg. the process the message should be sent to does not exist
	\item WRONG\_PRIORITY: a message priority is an integer greater than 1
    \item OUT\_OF\_MEMORY: message could not be sent because there was not enough memory available
\end{itemize}
\subsection*{Examples}
\begin{lstlisting}
envoyer_entier(parent,1,4);
envoyer_entier(waiter, END_OF_DINNER, 10);
\end{lstlisting}

\section{envoyer\_informations\_processus}

\texttt{int32\_t envoyer\_informations\_processus(int32\_t to, int32\_t priority)}

\subsection*{Description}
Sends a message containing information about the sender, called message of type process information. The information sent are the parent, the program id, the priority and the status (return value of a process when it exits), if any.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{to}: destination of the message to be sent to
 \item \textbf{data}: the int to be sent
 \item \textbf{priority}: priority of the message
\end{itemize}
\subsection*{Return values}
\begin{itemize}
	\item SUCCESS: the message has been sent
	\item FAILURE: something went wrong, eg. the process the message should be sent to does not exist
	\item WRONG\_PRIORITY: a message priority is an integer greater than 1
    \item OUT\_OF\_MEMORY: message could not be sent because there was not enough memory available
\end{itemize}
\subsection*{Examples}
\begin{lstlisting}
envoyer_informations_processus(parent, 4);
\end{lstlisting}

\section{recevoir\_premier}

\texttt{int32\_t recevoir\_premier(message\_t* message)}

\subsection*{Description}
The function receives the first message from the queue or waits until one arrives.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{message}: variable to write the received message into
\end{itemize}
\subsection*{Return values}
Returns SUCCESS in the case of success and FAILURE otherwise.

\subsection*{Examples}
\begin{lstlisting}
message_t m;
recevoir_premier(&m);
\end{lstlisting}    

\section{recevoir\_de}

\texttt{int32\_t recevoir\_de(int32\_t from, message\_t* message)}

\subsection*{Description}
Receives the first message from a given process or waits until one arrives.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{from}: pid to receive the message from
 \item \textbf{message}: variable to write the received message into
\end{itemize}
\subsection*{Return values}
Returns SUCCESS in the case of success and FAILURE otherwise.
\subsection*{Examples}
 \begin{lstlisting}
message_t m;
recevoir_de(parent_pid,&m);
\end{lstlisting}


\section{recevoir\_priorite}

\texttt{int32\_t recevoir\_priorite(int32\_t priority, message\_t* message)}

\subsection*{Description}
Receives the first message with the given priority. If there is not message with that priority, it waits until one arrives.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{priority}: priority that the received message should have
 \item \textbf{message}: variable to write the received message into
\end{itemize}
\subsection*{Return values}
Returns SUCCESS in the case of success and FAILURE otherwise.

\subsection*{Examples}
 \begin{lstlisting}
message_t m;
recevoir_priorite(2,&m);
recevoir_priorite(SUPERVISION_MESSAGE, &m)
 \end{lstlisting}


\section{recevoir\_premier\_delai}

\texttt{int32\_t recevoir\_premier\_delai(message\_t* message, uint32\_t timeout)}

\subsection*{Description}
Receives the first message of the message queue or waits until either one arrives or the specified time is up. In the last case, the call returns FAILURE and the caller resumes its execution.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{message}: variable to write the received message into
 \item \textbf{timeout}: time to wait in ms until the process resumes executing if a message does not arrive
\end{itemize}
\subsection*{Return values}
Returns SUCCESS if message has been read and FAILURE otherwise.

\subsection*{Examples}
 \begin{lstlisting}
message_t m;
recevoir_premier_delai(&m,2000);
 \end{lstlisting}


\section{recevoir\_de\_delai}

\texttt{int32\_t recevoir\_de\_delai(int32\_t from, message\_t* message, uint32\_t timeout)}

\subsection*{Description}
Receives the first message from a given process or waits until one arrives but only for a certain time.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{from}: pid to receive the message from
 \item \textbf{message}: variable to write the received message into
 \item \textbf{timeout}: time to wait in ms until the process resumes executing if a correct message does not arrive
\end{itemize}
\subsection*{Return values}
Returns SUCCESS if a message was read, FAILURE in the case of an error.

\subsection*{Examples}
 \begin{lstlisting}
message_t m;
recevoir_de_delai(17, &m, 3500);
...
if(recevoir_de_delai(waiter_pid, &m, 1000) != SUCCESS) {
...
 \end{lstlisting}


\section{recevoir\_priorite\_delai}

\texttt{int32\_t recevoir\_priorite\_delai(int32\_t priority, message\_t* message, uint32\_t timeout)}

\subsection*{Description}
Similar to the recevoir\_priorite() function. Receives the message with the correct priority or waits for a specified period of time. 
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{priority}: priority that the received message should have
 \item \textbf{message}: variable to write the received message into
 \item \textbf{timeout}: time to wait in ms until the process resumes executing if a correct message does not arrive
\end{itemize}
\subsection*{Return values}
Returns SUCCESS  in the case of successful reading of the message or FAILURE  in the case of failure of reading the message.
\subsection*{Examples}
 \begin{lstlisting}
message_t m;
recevoir_priorite_delai(2, &m, 3000);
recevoir_priorite_delai(SOME_PRIO, &m, SOME_TIME);
 \end{lstlisting}


\section{obtenir\_nombre\_messages}

\texttt{int32\_t obtenir\_nombre\_messages()}

\subsection*{Description}
Find out the number of messages the caller has in its queue. 
\subsection*{Parameters}
none
\subsection*{Return values}
Returns the number of messages the caller has in its message queue.
\subsection*{Examples}
 \begin{lstlisting}
 int number_of_messages = obtenir_nombre_messages();
 \end{lstlisting}


\section{superviser}

\texttt{int32\_t superviser(int32\_t supervised\_pid)}

\subsection*{Description}
The function registers the caller as the supervisor of a certain process. A supervisor automatically receives a message of type process information when the supervised process terminates. Those messages are the only ones with the priority SUPERVISION\_MESSAGE.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{supervised\_pid}: pid of the process to supervise
\end{itemize}
\subsection*{Return values}
Returns SUCCESS in the case of successfully registering the process as a supervisor, FAILURE otherwise.
\subsection*{Examples}
 \begin{lstlisting}
 superviser(17);
 superviser(child[0]);
 \end{lstlisting}

\section{stopper\_supervision}

\texttt{int32\_t stopper\_supervision(int32\_t supervised\_pid)}

\subsection*{Description}
The caller stops supervising a given process.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{supervised\_pid}: pid of the process to stop supervise.
\end{itemize}
\subsection*{Return values}
Returns SUCCESS if the function has been executed successfuly or FAILURE in the case of supervised\_pid not being supervised by the caller.
\subsection*{Examples}
 \begin{lstlisting}
stopper_supervision(17);
stopper_supervision(child[0]);
 \end{lstlisting}

\section{liberer\_message}

\texttt{int32\_t liberer\_message(message\_t mess)}

\subsection*{Description}
Frees memory taken by a message if the message is not needed anymore. It is recommended to explicitly use this function instead of liberer.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{message}: message to free 
\end{itemize}
\subsection*{Return values}
Returns SUCCESS in the case the operation being successful, FAILURE otherwise.
\subsection*{Examples}
 \begin{lstlisting}
message_t m;
recevoir_premier(&m);
...
liberer_message(m);
 \end{lstlisting}

\section{obtenir\_programme\_par\_id}

\texttt{char* obtenir\_programme\_par\_id(int32\_t program\_id)}

\subsection*{Description}
Returns the program name associated with this program\_id.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{program\_id}: pid of the program to retrieve name of
\end{itemize}
\subsection*{Return values}
Returns the name of the program associated with the given id, or NULL if the system ran out of memory or the given id does not match a program.
\subsection*{Examples}
 \begin{lstlisting}
ecrire(obtenir_programme_par_id(10));
ecrire(obtenir_programme_par_id(message_get_pinfo_program_id_value(m)));
 \end{lstlisting}
 
\section{obtenir\_programme\_aide}

\texttt{char* obtenir\_programme\_aide(const char* program\_name)}

\subsection*{Description}
The function returns the help of a program specified as a parameter 
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{program\_name}: name of the program whose help is required
\end{itemize}
\subsection*{Return values}
Returns a help description or NULL if the system is out of memory.
\subsection*{Examples}
 \begin{lstlisting}
 ecrire(obtenir_programme_aide(obtenir_programme_par_id(10)));
 char* help;
 help = obtenir_programme_aide(args[1]);
 ecrire(help);
\end{lstlisting}

\section{random}

\texttt{uint32\_t random(int* m\_w, int* m\_z)}

\subsection*{Description}
Returns a pseudo-random unsigned int. This is technically not a system call.
\subsection*{Parameters}
\begin{itemize}
 \item \textbf{m\_w}: some magic number 
 \item \textbf{m\_z}: another magic number
\end{itemize}
\subsection*{Return values}
Returns a pseudo-random unsigned integer.
\subsection*{Examples}
 \begin{lstlisting}
int m_w = 4000-philo_id, m_z = philo_id + 2000; //initializers for random numbers generation
while (true) {
    retarder(my_pid, random(&m_w,&m_z)%5000);
    ...
}
 \end{lstlisting}

